<?php
include "counter2.php";

pagestart();
print "<html>\n";
pagehead(_("How places work"));
print "<BODY bgcolor=\"white\">";
pagetop(_("How places work"));

print _("The way places work in the counter can sometimes be confusing.") .
"\n<br>\n" .
_("This note attempts to explain how it works a little bit.") .
"\n<p>\n" .
_("NOTE: This is valid as of Wed Feb 21 11:19:37 2001. Stuff changes without notice!");
print "\n<h2>" . _("The user input") . "</h2>\n" .
_("The user who registers is given three fields to fill in: Country, State and City.") . "<br>\n" .
_("For most city dwellers, the first and last will be obvious.") . "<br>\n" .
_("The middle one is obvious in some places (like the US), but far from obvious in other places.");

print "\n<h2>" . _("The places database") . "</h2>\n" .
_("The counter has a database of all places in the world. (hah!)") .
"\n<p>\n" .
_("For each place, it stores:") .
"\n<ol>" .
"\n<li>" . _("An unique number") . "</li>" .
"\n<li>" . _("A name (used in the matching routine below)") . "</li>" .
"\n<li>" . _("A longname (used when the place is mentioned)") . "</li>" .
"\n<li>" . _("A \"within\" field, showing which other place contains this place") . "<br>\n" .
_("Places form a strict hierarchy in the counter, unlike the real world.") . "</li>" .
"\n<li>" . _("Various info like hostcounts, population, usercounts and so on, which does not concern the placement of users.") . "</li>" .
"\n</ol>";

print "\n<h2>" . _("The matching process") . "</h2>\n" .
_("When someone enters a country, city and state, the matching routine forms two names:") .
"\n<ol>" .
"\n<li>" . _("Country:State:City") . "</li>" .
"\n<li>" . _("Country::City") . "</li>" .
"\n</ol>\n";
print _("These are formed by taking the user input, imagining that it is in the ISO 8859-1 charset, folding it to a reasonable approximation in ASCII, and regularizing spaces and punctuation. Both are looked up through the alias process.") .
"\n<p>\n" .
_("The alias process does the following steps:") .
"\n<ol>" .
"\n<li>" . _("Look up the name") . "</li>" .
"\n<li>" . _("If not found, remove the last colon (:) and everything following, and try again from 1.") .
"\n<li>" . _("If found, and type is alias, use the \"within\" field of the record to find the aliased record. Do 3 again (and give warning) if it is still an alias.") .
"\n<li>" . _("If step 2 removed something, add it back onto the found alias, and start over again from step 1.") . "<br>\n" .
_("This allows aliases for countries and states to find cities, for instance.") .
"\n</ol>\n";
print _("If both the names formed in the matching routine return something, the name with the most components (largest number of colons) wins.") .
"\n<br>\n" .
_("If neither returns anything (for instance when the country is misspelled in an unique way), the email address of the user is checked to see if one can infer a country from that.") .
"\n<br>\n" .
_("The result of the lookup is stored as a name (not a number!) in the \"placeid\" field of the person record, and the type of lookup (place, alias or email) is stored in the \"placesource\" field of the person record.") .
"\n<p>\n" .
_("For those interested in source, this is in the \"lib/Validate/Places.pm\" file, in the \"getbyname\" subroutine.") .
"\n<p>\n" .
_("(Parenthesis: One reason for the arcaneness of the subroutine is that it actually does no search; all lookups are exact. This was thought at the time to be a speed advantage...)");

print "\n<h2>" . _("The reporting hierarchy") . "</h2>\n" .
_("When preparing the list of places and persons within them, the counter strictly follows the links given by the \"Within\" fields, starting at the root (\"All\").") .
"\n<p>\n" .
_("All places within the place are listed in alphabetical order by longname (not name!), followed by a list of users at this exact place.") . " <em>" . _("This will change") . "!</em>" .
"\n<p>\n" .
_("This means that the naming of places") . " <em>" . _("does not matter") . "</em> " . _("in the published user lists.");

print "\n<h2>" . _("Points to ponder") . "</h2>\n" .
_("These are things to think about. I do not know if they are answers.") .
"\n<p>\n" .
_("When cities are unique within a country, it may be best to name them as \"country::city\". This will mean that people are placed in the same city no matter how they spell their state.") . "<br>\n" .
_("If this is the case for all cities in a country, adding states is only a way to control the listing of places. This can be nice.") .
"\n<p>\n" .
_("It is perfectly possible to have multiple levels of state. However, the state field is single in the matching algorithm. It does not make sense to have \"country:state:state:city\" as the name of a place; the matching algorithm will never construct a name that fits this.") .
"\n<p>\n" .
_("When people live outside a city, they frequently put some small subdivision (\"county\") as either their state or their city, essentially at random. It is hard to know what to do here.") .
"\n<p>\n" .
_("The current sad state of charsets on the Web means that some people will enter data that is in some other charset than ISO-8859-1, like Shift-JIS, KOI-8 or 8859-2. This data will look quite ugly when \"converted\" to ASCII under the assumption that it is ISO 8859-1, leading to aliases like \"PL::Lod4\" for the Polish city of Lodz (the character in 8859-2 that represents Z with hacek is a superscript 4 in 8859-1).") .
"\n<p>\n" .
_("Ultimately, the counter will switch to UTF-8 for its internal representation, and try to get proper charset marking on data coming from users. This may (or may not) help.");


pagebottom("yes");
print "\n</body>\n" .
"</html>";
?>


